home *** CD-ROM | disk | FTP | other *** search
/ Languguage OS 2 / Languguage OS II Version 10-94 (Knowledge Media)(1994).ISO / gnu / elispman.lha / elispman / elisp-26 (.txt) < prev    next >
GNU Info File  |  1993-06-01  |  49KB  |  877 lines

  1. This is Info file elisp, produced by Makeinfo-1.55 from the input file
  2. elisp.texi.
  3.    This is edition 2.0 of the GNU Emacs Lisp Reference Manual, for
  4. Emacs Version 19.
  5.    Published by the Free Software Foundation, 675 Massachusetts Avenue,
  6. Cambridge, MA 02139 USA
  7.    Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
  8.    Permission is granted to make and distribute verbatim copies of this
  9. manual provided the copyright notice and this permission notice are
  10. preserved on all copies.
  11.    Permission is granted to copy and distribute modified versions of
  12. this manual under the conditions for verbatim copying, provided that
  13. the entire resulting derived work is distributed under the terms of a
  14. permission notice identical to this one.
  15.    Permission is granted to copy and distribute translations of this
  16. manual into another language, under the above conditions for modified
  17. versions, except that this permission notice may be stated in a
  18. translation approved by the Foundation.
  19. File: elisp,  Node: Abbrev Tables,  Next: Defining Abbrevs,  Prev: Abbrev Mode,  Up: Abbrevs
  20. Abbrev Tables
  21. =============
  22.    This section describes how to create and manipulate abbrev tables.
  23.  - Function: make-abbrev-table
  24.      This function creates and returns a new, empty abbrev table--an
  25.      obarray containing no symbols.  It is a vector filled with `nil's.
  26.  - Function: clear-abbrev-table TABLE
  27.      This function undefines all the abbrevs in abbrev table TABLE,
  28.      leaving it empty.  The function returns `nil'.
  29.  - Function: define-abbrev-table TABNAME DEFINITIONS
  30.      This function defines TABNAME (a symbol) as an abbrev table name,
  31.      i.e., as a variable whose value is an abbrev table.  It defines
  32.      abbrevs in the table according to DEFINITIONS, a list of elements
  33.      of the form `(ABBREVNAME EXPANSION HOOK USECOUNT)'.  The value is
  34.      always `nil'.
  35.  - Variable: abbrev-table-name-list
  36.      This is a list of symbols whose values are abbrev tables.
  37.      `define-abbrev-table' adds the new abbrev table name to this list.
  38.  - Function: insert-abbrev-table-description NAME &optional HUMAN
  39.      This function inserts before point a description of the abbrev
  40.      table named NAME.  The argument NAME is a symbol whose value is an
  41.      abbrev table.  The value is always `nil'.
  42.      If HUMAN is non-`nil', a human-oriented description is inserted.
  43.      Otherwise the description is a Lisp expression--a call to
  44.      `define-abbrev-table' which would define NAME exactly as it is
  45.      currently defined.
  46. File: elisp,  Node: Defining Abbrevs,  Next: Abbrev Files,  Prev: Abbrev Tables,  Up: Abbrevs
  47. Defining Abbrevs
  48. ================
  49.    These functions define an abbrev in a specified abbrev table.
  50. `define-abbrev' is the low-level basic function, while `add-abbrev' is
  51. used by commands that ask for information from the user.
  52.  - Function: add-abbrev TABLE TYPE ARG
  53.      This function adds an abbreviation to abbrev table TABLE.  The
  54.      argument TYPE is a string describing in English the kind of abbrev
  55.      this will be (typically, `"global"' or `"mode-specific"'); this is
  56.      used in prompting the user.  The argument ARG is the number of
  57.      words in the expansion.
  58.      The return value is the symbol which internally represents the new
  59.      abbrev, or `nil' if the user declines to redefine an existing
  60.      abbrev.
  61.  - Function: define-abbrev TABLE NAME EXPANSION HOOK
  62.      This function defines an abbrev in TABLE named NAME, to expand to
  63.      EXPANSION, and call HOOK.  The return value is an uninterned
  64.      symbol which represents the abbrev inside Emacs; its name is NAME.
  65.      The argument NAME should be a string.  The argument EXPANSION
  66.      should be a string, or `nil', to undefine the abbrev.
  67.      The argument HOOK is a function or `nil'.  If HOOK is non-`nil',
  68.      then it is called with no arguments after the abbrev is replaced
  69.      with EXPANSION; point is located at the end of EXPANSION.
  70.      The use count of the abbrev is initialized to zero.
  71.  - User Option: only-global-abbrevs
  72.      If this variable is non-`nil', it means that the user plans to use
  73.      global abbrevs only.  This tells the commands that define
  74.      mode-specific abbrevs to define global ones instead.  This
  75.      variable does not alter the functioning of the functions in this
  76.      section; it is examined by their callers.
  77. File: elisp,  Node: Abbrev Files,  Next: Abbrev Expansion,  Prev: Defining Abbrevs,  Up: Abbrevs
  78. Saving Abbrevs in Files
  79. =======================
  80.    A file of saved abbrev definitions is actually a file of Lisp code.
  81. The abbrevs are saved in the form of a Lisp program to define the same
  82. abbrev tables with the same contents.  Therefore, you can load the file
  83. with `load' (*note How Programs Do Loading::.).  However, the function
  84. `quietly-read-abbrev-file' is provided as a more convenient interface.
  85.    User-level facilities such as `save-some-buffers' can save abbrevs
  86. in a file automatically, under the control of variables described here.
  87.  - User Option: abbrev-file-name
  88.      This is the default file name for reading and saving abbrevs.
  89.  - Function: quietly-read-abbrev-file FILENAME
  90.      This function reads abbrev definitions from a file named FILENAME,
  91.      previously written with `write-abbrev-file'.  If FILENAME is
  92.      `nil', the file specified in `abbrev-file-name' is used.
  93.      `save-abbrevs' is set to `t' so that changes will be saved.
  94.      This function does not display any messages.  It returns `nil'.
  95.  - User Option: save-abbrevs
  96.      A non-`nil' value for `save-abbrev' means that Emacs should save
  97.      abbrevs when files are saved.  `abbrev-file-name' specifies the
  98.      file to save the abbrevs in.
  99.  - Variable: abbrevs-changed
  100.      This variable is set non-`nil' by defining or altering any
  101.      abbrevs.  This serves as a flag for various Emacs commands to
  102.      offer to save your abbrevs.
  103.  - Command: write-abbrev-file FILENAME
  104.      Save all abbrev definitions, in all abbrev tables, in the file
  105.      FILENAME, in the form of a Lisp program which when loaded will
  106.      define the same abbrevs.  This function returns `nil'.
  107. File: elisp,  Node: Abbrev Expansion,  Next: Standard Abbrev Tables,  Prev: Abbrev Files,  Up: Abbrevs
  108. Looking Up and Expanding Abbreviations
  109. ======================================
  110.    Abbrevs are usually expanded by commands for interactive use,
  111. including `self-insert-command'.  This section describes the
  112. subroutines used in writing such functions, as well as the variables
  113. they use for communication.
  114.  - Function: abbrev-symbol ABBREV &optional TABLE
  115.      This function returns the symbol representing the abbrev named
  116.      ABBREV.  The value returned is `nil' if that abbrev is not
  117.      defined.  The optional second argument TABLE is the abbrev table
  118.      to look it up in.  By default, this function tries first the
  119.      current buffer's local abbrev table, and second the global abbrev
  120.      table.
  121.  - User Option: abbrev-all-caps
  122.      When this is set non-`nil', an abbrev entered entirely in upper
  123.      case is expanded using all upper case.  Otherwise, an abbrev
  124.      entered entirely in upper case is expanded by capitalizing each
  125.      word of the expansion.
  126.  - Function: abbrev-expansion ABBREV &optional TABLE
  127.      This function returns the string that ABBREV would expand into (as
  128.      defined by the abbrev tables used for the current buffer).  The
  129.      optional argument TABLE specifies the abbrev table to use; if it is
  130.      specified, the abbrev is looked up in that table only.
  131.  - Variable: abbrev-start-location
  132.      This is the buffer position for `expand-abbrev' to use as the start
  133.      of the next abbrev to be expanded.  (`nil' means use the word
  134.      before point instead.)  `abbrev-start-location' is set to `nil'
  135.      each time `expand-abbrev' is called.  This variable is also set by
  136.      `abbrev-prefix-mark'.
  137.  - Variable: abbrev-start-location-buffer
  138.      The value of this variable is the buffer for which
  139.      `abbrev-start-location' has been set.  Trying to expand an abbrev
  140.      in any other buffer clears `abbrev-start-location'.  This variable
  141.      is set by `abbrev-prefix-mark'.
  142.  - Variable: last-abbrev
  143.      This is the `abbrev-symbol' of the last abbrev expanded.  This
  144.      information is left by `expand-abbrev' for the sake of the
  145.      `unexpand-abbrev' command.
  146.  - Variable: last-abbrev-location
  147.      This is the location of the last abbrev expanded.  This contains
  148.      information left by `expand-abbrev' for the sake of the
  149.      `unexpand-abbrev' command.
  150.  - Variable: last-abbrev-text
  151.      This is the exact expansion  text of the last abbrev expanded, as
  152.      results from case conversion.  Its value is `nil' if the abbrev
  153.      has already been unexpanded.  This contains information left by
  154.      `expand-abbrev' for the sake of the `unexpand-abbrev' command.
  155.  - Variable: pre-abbrev-expand-hook
  156.      This is a normal hook whose functions are executed, in sequence,
  157.      just before any expansion of an abbrev.  *Note Hooks::.  Since it
  158.      is a normal hook, the hook functions receive no arguments.
  159.      However, they can find the abbrev to be expanded by looking in the
  160.      buffer before point.
  161.    The following sample code shows a simple use of
  162. `pre-abbrev-expand-hook'.  If the user terminates an abbrev with a
  163. punctuation character, the function issues a prompt.  Thus, this hook
  164. allows the user to decide whether the abbrev should be expanded, and to
  165. abort expansion if it is not desired.
  166.      (add-hook 'pre-abbrev-expand-hook 'query-if-not-space)
  167.      
  168.      ;; This is the function invoked by `pre-abbrev-expand-hook'.
  169.      
  170.      ;; If the user terminated the abbrev with a space, the function does
  171.      ;; nothing (that is, it returns so that the abbrev can expand).  If the
  172.      ;; user entered some other character, this function asks whether
  173.      ;; expansion should continue.
  174.      
  175.      ;; If the user enters the prompt with `y', the function returns
  176.      ;; `nil' (because of the `not' function), but that is
  177.      ;; acceptable; the return value has no effect on expansion.
  178.      
  179.      (defun query-if-not-space ()
  180.        (if (/= ?\  (preceding-char))
  181.            (if (not (y-or-n-p "Do you want to expand this abbrev? "))
  182.                (error "Not expanding this abbrev"))))
  183. File: elisp,  Node: Standard Abbrev Tables,  Prev: Abbrev Expansion,  Up: Abbrevs
  184. Standard Abbrev Tables
  185. ======================
  186.    Here we list the variables that hold the abbrev tables for the
  187. preloaded major modes of Emacs.
  188.  - Variable: global-abbrev-table
  189.      This is the abbrev table for mode-independent abbrevs.  The abbrevs
  190.      defined in it apply to all buffers.  Each buffer may also have a
  191.      local abbrev table, whose abbrev definitions take precedence over
  192.      those in the global table.
  193.  - Variable: local-abbrev-table
  194.      The value of this buffer-local variable is the (mode-specific)
  195.      abbreviation table of the current buffer.
  196.  - Variable: fundamental-mode-abbrev-table
  197.      This is the local abbrev table used in Fundamental mode.  It is the
  198.      local abbrev table in all buffers in Fundamental mode.
  199.  - Variable: text-mode-abbrev-table
  200.      This is the local abbrev table used in Text mode.
  201.  - Variable: c-mode-abbrev-table
  202.      This is the local abbrev table used in C mode.
  203.  - Variable: lisp-mode-abbrev-table
  204.      This is the local abbrev table used in Lisp mode and Emacs Lisp
  205.      mode.
  206. File: elisp,  Node: Processes,  Next: System Interface,  Prev: Abbrevs,  Up: Top
  207. Processes
  208. *********
  209.    In the terminology of operating systems, a "process" is a space in
  210. which a program can execute.  Emacs runs in a process.  Emacs Lisp
  211. programs can invoke other programs in processes of their own.  These are
  212. called "subprocesses" or "child processes" of the Emacs process, which
  213. is their "parent process".
  214.    A subprocess of Emacs may be "synchronous" or "asynchronous",
  215. depending on how it is created.  When you create a synchronous
  216. subprocess, the Lisp program waits for the subprocess to terminate
  217. before continuing execution.  When you create an asynchronous
  218. subprocess, it can run in parallel with the Lisp program.  This kind of
  219. subprocess is represented within Emacs by a Lisp object which is also
  220. called a "process".  Lisp programs can use this object to communicate
  221. with the subprocess or to control it.  For example, you can send
  222. signals, obtain status information, receive output from the process, or
  223. send input to it.
  224.  - Function: processp OBJECT
  225.      This function returns `t' if OBJECT is a process, `nil' otherwise.
  226. * Menu:
  227. * Subprocess Creation::      Functions that start subprocesses.
  228. * Synchronous Processes::    Details of using synchronous subprocesses.
  229. * Asynchronous Processes::   Starting up an asynchronous subprocess.
  230. * Deleting Processes::       Eliminating an asynchronous subprocess.
  231. * Process Information::      Accessing run-status and other attributes.
  232. * Input to Processes::       Sending input to an asynchronous subprocess.
  233. * Signals to Processes::     Stopping, continuing or interrupting
  234.                                an asynchronous subprocess.
  235. * Output from Processes::    Collecting output from an asynchronous subprocess.
  236. * Sentinels::                Sentinels run when process run-status changes.
  237. * Transaction Queues::         Transaction-based communication with subprocesses.
  238. * TCP::                      Opening network connections.
  239. File: elisp,  Node: Subprocess Creation,  Next: Synchronous Processes,  Up: Processes
  240. Functions that Create Subprocesses
  241. ==================================
  242.    There are three functions that create a new subprocess in which to
  243. run a program.  One of them, `start-process', creates an asynchronous
  244. process and returns a process object (*note Asynchronous Processes::.).
  245. The other two, `call-process' and `call-process-region', create a
  246. synchronous process and do not return a process object (*note
  247. Synchronous Processes::.).
  248.    Synchronous and asynchronous processes are explained in following
  249. sections.  Since the three functions are all called in a similar
  250. fashion, their common arguments are described here.
  251.    In all cases, the function's PROGRAM argument specifies the program
  252. to be run.  An error is signaled if the file is not found or cannot be
  253. executed.  The actual file containing the program is found by following
  254. normal system rules: if the file name is absolute, then the program
  255. must be found in the specified file; if the name is relative, then the
  256. directories in `exec-path' are searched sequentially for a suitable
  257. file.  The variable `exec-path' is initialized when Emacs is started,
  258. based on the value of the environment variable `PATH'.  The standard
  259. file name constructs, `~', `.', and `..', are interpreted as usual in
  260. `exec-path', but environment variable substitutions (`$HOME', etc.) are
  261. not recognized; use `substitute-in-file-name' to perform them (*note
  262. File Name Expansion::.).
  263.    Each of the subprocess-creating functions has a BUFFER-OR-NAME
  264. argument which specifies where the standard output from the program will
  265. go.  If BUFFER-OR-NAME is `nil', that says to discard the output unless
  266. a filter function handles it.  (*Note Filter Functions::, and *Note
  267. Streams::.)  Normally, you should avoid having multiple processes send
  268. output to the same buffer because their output would be intermixed
  269. randomly.
  270.    All three of the subprocess-creating functions have a `&rest'
  271. argument, ARGS.  The ARGS must all be strings, and they are supplied to
  272. PROGRAM as separate command line arguments.  Wildcard characters and
  273. other shell constructs are not allowed in these strings, since they are
  274. passed directly to the specified program.
  275.    *Please note:* the argument PROGRAM contains only the name of the
  276. program; it may not contain any command-line arguments.  Such arguments
  277. must be provided via ARGS.
  278.    The subprocess gets its current directory from the value of
  279. `default-directory' (*note File Name Expansion::.).
  280.    The subprocess inherits its environment from Emacs; but you can
  281. specify overrides for it with `process-environment'.  *Note System
  282. Environment::.
  283.  - Variable: exec-directory
  284.      The value of this variable is the name of a directory (a string)
  285.      that contains programs that come with GNU Emacs, that are intended
  286.      for Emacs to invoke.  The program `wakeup' is an example of such a
  287.      program; the `display-time' command uses it to get a reminder once
  288.      per minute.
  289.      The default value is the name of a directory whose name ends in
  290.      `arch-lib'.  We call the directory `emacs/arch-lib', since its
  291.      name usually ends that way.  We sometimes refer to "the directory
  292.      `emacs/arch-lib'," when strictly speaking we ought to say, "the
  293.      directory named by the variable `exec-directory'."  Most of the
  294.      time, there is no difference.
  295.      (In earlier Emacs versions, prior to version 19, these files lived
  296.      in the directory `emacs/etc' instead of in `emacs/arch-lib'.)
  297.  - User Option: exec-path
  298.      The value of this variable is a list of directories to search for
  299.      programs to run in subprocesses.  Each element is either the name
  300.      of a directory (i.e., a string), or `nil', which stands for the
  301.      default directory (which is the value of `default-directory').
  302.      The value of `exec-path' is used by `call-process' and
  303.      `start-process' when the PROGRAM argument is not an absolute file
  304.      name.
  305. File: elisp,  Node: Synchronous Processes,  Next: Asynchronous Processes,  Prev: Subprocess Creation,  Up: Processes
  306. Creating a Synchronous Process
  307. ==============================
  308.    After a "synchronous process" is created, Emacs waits for the
  309. process to terminate before continuing.  Starting Dired is an example of
  310. this: it runs `ls' in a synchronous process, then modifies the output
  311. slightly.  Because the process is synchronous, the entire directory
  312. listing arrives in the buffer before Emacs tries to do anything with it.
  313.    While Emacs waits for the synchronous subprocess to terminate, the
  314. user can quit by typing `C-g', and the process is killed by sending it
  315. a `SIGKILL' signal.  *Note Quitting::.
  316.    The synchronous subprocess functions return `nil' in version 18.  In
  317. version 19, they will return an indication of how the process
  318. terminated.
  319.  - Function: call-process PROGRAM &optional INFILE BUFFER-OR-NAME
  320.           DISPLAY &rest ARGS
  321.      This function calls PROGRAM in a separate process and waits for it
  322.      to finish.
  323.      The standard input for the process comes from file INFILE if
  324.      INFILE is not `nil' and from `/dev/null' otherwise.  The process
  325.      output gets inserted in buffer BUFFER-OR-NAME before point, if
  326.      that argument names a buffer.  If BUFFER-OR-NAME is `t', output is
  327.      sent to the current buffer; if BUFFER-OR-NAME is `nil', output is
  328.      discarded.
  329.      If BUFFER-OR-NAME is the integer 0, `call-process' returns `nil'
  330.      immediately and discards any output.  In this case, the process is
  331.      not truly synchronous, since it can run in parallel with Emacs;
  332.      but you can think of it as synchronous in that Emacs is
  333.      essentially finished with the subprocess as soon as this function
  334.      returns.
  335.      If DISPLAY is non-`nil', then `call-process' redisplays the buffer
  336.      as output is inserted.  Otherwise the function does no redisplay,
  337.      and the results become visible on the screen only when Emacs
  338.      redisplays that buffer in the normal course of events.
  339.      The remaining arguments, ARGS, are strings that are supplied as
  340.      the command line arguments for the program.
  341.      The value returned by `call-process' (unless you told it not to
  342.      wait) indicates the reason for process termination.  A number
  343.      gives the exit status of the subprocess; 0 means success, and any
  344.      other value means failure.  If the process terminated with a
  345.      signal, `call-process' returns a string describing the signal.
  346.      The examples below are both run with the buffer `foo' current.
  347.           (call-process "pwd" nil t)
  348.                => nil
  349.           
  350.           ---------- Buffer: foo ----------
  351.           /usr/user/lewis/manual
  352.           ---------- Buffer: foo ----------
  353.           (call-process "grep" nil "bar" nil "lewis" "/etc/passwd")
  354.                => nil
  355.           
  356.           ---------- Buffer: bar ----------
  357.           lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh
  358.           
  359.           ---------- Buffer: bar ----------
  360.      The `dired-readin' function contains a good example of the use of
  361.      `call-process':
  362.           (call-process
  363.            "ls" nil buffer nil dired-listing-switches dirname)
  364.  - Function: call-process-region START END PROGRAM &optional DELETE
  365.           BUFFER-OR-NAME DISPLAY &rest ARGS
  366.      This function sends the text between START to END as standard
  367.      input to a process running PROGRAM.  It deletes the text sent if
  368.      DELETE is non-`nil', which may be useful when the output is going
  369.      to be inserted back in the current buffer.
  370.      If BUFFER-OR-NAME names a buffer, the output is inserted in that
  371.      buffer at point.  If BUFFER-OR-NAME is `t', the output is sent to
  372.      the current buffer.  If BUFFER-OR-NAME is `nil', the output is
  373.      discarded.  If BUFFER-OR-NAME is the integer 0, the output is
  374.      discarded and `call-process' returns `nil' immediately, just as
  375.      `call-process' would.
  376.      If DISPLAY is non-`nil', then `call-process-region' redisplays the
  377.      buffer as output is inserted.  Otherwise the function does no
  378.      redisplay, and the results become visible on the screen only when
  379.      Emacs redisplays that buffer in the normal course of events.
  380.      The remaining arguments, ARGS, are strings that are supplied as
  381.      the command line arguments for the program.
  382.      The return value of `call-process-region' is just like that of
  383.      `call-process': `nil' if you told it to return without waiting;
  384.      otherwise, a number or string which indicates how the subprocess
  385.      terminated.
  386.      In the following example, we use `call-process-region' to run the
  387.      `cat' utility, with standard input being the first five characters
  388.      in buffer `foo' (the word `input').  `cat' copies its standard
  389.      input into its standard output.  Since the argument BUFFER-OR-NAME
  390.      is `t', this output is inserted in the current buffer.
  391.           ---------- Buffer: foo ----------
  392.           input-!-
  393.           ---------- Buffer: foo ----------
  394.           (call-process-region 1 6 "cat" nil t)
  395.                => nil
  396.           
  397.           ---------- Buffer: foo ----------
  398.           inputinput-!-
  399.           ---------- Buffer: foo ----------
  400.      The `shell-command-on-region' command uses `call-process-region'
  401.      like this:
  402.           (call-process-region
  403.            start end
  404.            shell-file-name      ; Name of program.
  405.            nil                  ; Do not delete region.
  406.            buffer               ; Send output to `buffer'.
  407.            nil                  ; No redisplay during output.
  408.            "-c" command)        ; Arguments for the shell.
  409. File: elisp,  Node: Asynchronous Processes,  Next: Deleting Processes,  Prev: Synchronous Processes,  Up: Processes
  410. Creating an Asynchronous Process
  411. ================================
  412.    After an "asynchronous process" is created, Emacs and the Lisp
  413. program can continue running immediately.  The process may thereafter
  414. run in parallel with Emacs, and the two may communicate with each other
  415. using the functions described in following sections.  Here we describe
  416. how to create an asynchronous process, with `start-process'.
  417.  - Function: start-process NAME BUFFER-OR-NAME PROGRAM &rest ARGS
  418.      This function creates a new asynchronous subprocess and starts the
  419.      program PROGRAM running in it.  It returns a process object that
  420.      stands for the new subprocess for Emacs Lisp programs.  The
  421.      argument NAME specifies the name for the process object; if a
  422.      process with this name already exists, then NAME is modified (by
  423.      adding `<1>', etc.) to be unique.  The buffer BUFFER-OR-NAME is the
  424.      buffer to associate with the process.
  425.      The remaining arguments, ARGS, are strings that are supplied as
  426.      the command line arguments for the program.
  427.      In the example below, the first process is started and runs
  428.      (rather, sleeps) for 100 seconds.  Meanwhile, the second process
  429.      is started, given the name `my-process<1>' for the sake of
  430.      uniqueness.  It inserts the directory listing at the end of the
  431.      buffer `foo', before the first process finishes.  Then it
  432.      finishes, and a message to that effect is inserted in the buffer.
  433.      Much later, the first process finishes, and another message is
  434.      inserted in the buffer for it.
  435.           (start-process "my-process" "foo" "sleep" "100")
  436.                => #<process my-process>
  437.           (start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin")
  438.                => #<process my-process<1>>
  439.           
  440.           ---------- Buffer: foo ----------
  441.           total 2
  442.           lrwxrwxrwx  1 lewis     14 Jul 22 10:12 gnuemacs --> /emacs
  443.           -rwxrwxrwx  1 lewis     19 Jul 30 21:02 lemon
  444.           
  445.           Process my-process<1> finished
  446.           
  447.           Process my-process finished
  448.           ---------- Buffer: foo ----------
  449.  - Function: start-process-shell-command NAME BUFFER-OR-NAME COMMAND
  450.           &rest COMMAND-ARGS
  451.      This function is like `start-process' except that it uses a shell
  452.      to execute the specified command.  The argument COMMAND is a shell
  453.      command name, and COMMAND-ARGS are the arguments for the shell
  454.      command.
  455.  - Variable: process-connection-type
  456.      This variable controls the type of device used to communicate with
  457.      asynchronous subprocesses.  If it is `nil', then pipes are used.
  458.      If it is `t', then PTYs are used (or pipes if PTYs are not
  459.      supported).
  460.      PTYs are usually preferable for processes visible to the user, as
  461.      in Shell mode, because they allow job control (`C-c', `C-z', etc.)
  462.      to work between the process and its children whereas pipes do not.
  463.      For subprocesses used for internal purposes by programs, it is
  464.      often better to use a pipe, because they are more efficient.  In
  465.      addition, the total number of PTYs is limited on many systems and
  466.      it is good not to waste them.
  467.      The value `process-connection-type' is used when `start-process'
  468.      is called, so in order to change it for just one call of
  469.      `start-process', temporarily rebind it with `let'.
  470.           (let ((process-connection-type nil))  ; Use a pipe.
  471.             (start-process ...))
  472. File: elisp,  Node: Deleting Processes,  Next: Process Information,  Prev: Asynchronous Processes,  Up: Processes
  473. Deleting Processes
  474. ==================
  475.    "Deleting a process" disconnects Emacs immediately from the
  476. subprocess, and removes it from the list of active processes.  It sends
  477. a signal to the subprocess to make the subprocess terminate, but this is
  478. not guaranteed to happen immediately.  (The process object itself
  479. continues to exist as long as other Lisp objects point to it.)
  480.    You can delete a process explicitly at any time.  Processes are
  481. deleted automatically after they terminate, but not necessarily right
  482. away.  If you delete a terminated process explicitly before it is
  483. deleted automatically, no harm results.
  484.  - Variable: delete-exited-processes
  485.      This variable controls automatic deletion of processes that have
  486.      terminated (due to calling `exit' or to a signal).  If it is
  487.      `nil', then they continue to exist until the user runs
  488.      `list-processes'.  Otherwise, they are deleted immediately after
  489.      they exit.
  490.  - Function: delete-process NAME
  491.      This function deletes the process associated with NAME.  The
  492.      argument NAME may be a process, the name of a process, a buffer,
  493.      or the name of a buffer.  The subprocess is killed with a `SIGHUP'
  494.      signal.
  495.           (delete-process "*shell*")
  496.                => nil
  497.  - Function: process-kill-without-query PROCESS
  498.      This function declares that Emacs need not query the user if
  499.      PROCESS is still running when Emacs is exited.  The process will
  500.      be deleted silently.  The value is `t'.
  501.           (process-kill-without-query (get-process "shell"))
  502.                => t
  503. File: elisp,  Node: Process Information,  Next: Input to Processes,  Prev: Deleting Processes,  Up: Processes
  504. Process Information
  505. ===================
  506.    Several functions return information about processes.
  507. `list-processes' is provided for interactive use.
  508.  - Command: list-processes
  509.      This command displays a listing of all living processes.  (Any
  510.      processes listed as `Exited' or `Signaled' are actually eliminated
  511.      after the listing is made.)  This function returns `nil'.
  512.  - Function: process-list
  513.      This function returns a list of all processes that have not been
  514.      deleted.
  515.           (process-list)
  516.                => (#<process display-time> #<process shell>)
  517.  - Function: get-process NAME
  518.      This function returns the process named NAME, or `nil' if there is
  519.      none.  An error is signaled if NAME is not a string.
  520.           (get-process "shell")
  521.                => #<process shell>
  522.  - Function: process-command PROCESS
  523.      This function returns the command that was executed to start
  524.      PROCESS.  This is a list of strings, the first string being the
  525.      program executed and the rest of the strings being the arguments
  526.      that were given to the program.
  527.           (process-command (get-process "shell"))
  528.                => ("/bin/csh" "-i")
  529.  - Function: process-exit-status PROCESS
  530.      This function returns the exit status of PROCESS or the signal
  531.      number that killed it.  (Use the result of `process-status' to
  532.      determine which of those it is.)  If PROCESS has not yet
  533.      terminated, the value is 0.
  534.  - Function: process-id PROCESS
  535.      This function returns the PID of PROCESS.  This is an integer
  536.      which distinguishes the process PROCESS from all other processes
  537.      running on the same computer at the current time.  The PID of a
  538.      process is chosen by the operating system kernel when the process
  539.      is started and remains constant as long as the process exists.
  540.  - Function: process-name PROCESS
  541.      This function returns the name of PROCESS.
  542.  - Function: process-status PROCESS-NAME
  543.      This function returns the status of PROCESS-NAME as a symbol.  The
  544.      argument PROCESS-NAME must be either a process or a string.  If it
  545.      is a string, it need not name an actual process.
  546.      The possible values for an actual subprocess are:
  547.     `run'
  548.           for a process that is running.
  549.     `stop'
  550.           for a process that is stopped but continuable.
  551.     `exit'
  552.           for a process that has exited.
  553.     `signal'
  554.           for a process that has received a fatal signal.
  555.     `open'
  556.           for a network connection that is open.
  557.     `closed'
  558.           for a network connection that is closed.  Once a connection
  559.           is closed, you cannot reopen it, though you might be able to
  560.           open a new connection to the same place.
  561.     `nil'
  562.           if PROCESS-NAME is not the name of an existing process.
  563.           (process-status "shell")
  564.                => run
  565.           (process-status "never-existed")
  566.                => nil
  567.           x
  568.                => #<process xx<1>>
  569.           (process-status x)
  570.                => exit
  571.      For a network connection, `process-status' returns one of the
  572.      symbols `open' or `closed'.  The latter means that the other side
  573.      closed the connection, or Emacs did `delete-process'.
  574.      In earlier Emacs versions (prior to version 19), the status of a
  575.      network connection was `run' if open, and `exit' if closed.
  576. File: elisp,  Node: Input to Processes,  Next: Signals to Processes,  Prev: Process Information,  Up: Processes
  577. Sending Input to Processes
  578. ==========================
  579.    Asynchronous subprocesses receive input when it is sent to them by
  580. Emacs, which is done with the functions in this section.  You must
  581. specify the process to send input to, and the input data to send.  The
  582. data appears on the "standard input" of the subprocess.
  583.    Some operating systems have limited space for buffered input in a
  584. PTY.  On these systems, the subprocess will cease to read input
  585. correctly if you send an input line longer than the system can handle.
  586. You cannot avoid the problem by breaking the input into pieces and
  587. sending them separately, for the operating system will still have to put
  588. all the pieces together in the input buffer before it lets the
  589. subprocess read the line.  The only solution is to put the input in a
  590. temporary file, and send the process a brief command to read that file.
  591.  - Function: process-send-string PROCESS-NAME STRING
  592.      This function sends PROCESS-NAME the contents of STRING as
  593.      standard input.  The argument PROCESS-NAME must be a process or
  594.      the name of a process.
  595.      The function returns `nil'.
  596.           (process-send-string "shell<1>" "ls\n")
  597.                => nil
  598.           ---------- Buffer: *shell* ----------
  599.           ...
  600.           introduction.texi               syntax-tables.texi~
  601.           introduction.texi~              text.texi
  602.           introduction.txt                text.texi~
  603.           ...
  604.           ---------- Buffer: *shell* ----------
  605.  - Command: process-send-region PROCESS-NAME START END
  606.      This function sends the text in the region defined by START and
  607.      END as standard input to PROCESS-NAME, which is a process or a
  608.      process name.
  609.      An error is signaled unless both START and END are integers or
  610.      markers that indicate positions in the current buffer.  (It is
  611.      unimportant which number is larger.)
  612.  - Function: process-send-eof &optional PROCESS-NAME
  613.      This function makes PROCESS-NAME see an end-of-file in its input.
  614.      The EOF comes after any text already sent to it.
  615.      If PROCESS-NAME is not supplied, or if it is `nil', then this
  616.      function sends the EOF to the current buffer's process.  An error
  617.      is signaled if the current buffer has no process.
  618.      The function returns PROCESS-NAME.
  619.           (process-send-eof "shell")
  620.                => "shell"
  621. File: elisp,  Node: Signals to Processes,  Next: Output from Processes,  Prev: Input to Processes,  Up: Processes
  622. Sending Signals to Processes
  623. ============================
  624.    "Sending a signal" to a subprocess is a way of interrupting its
  625. activities.  There are several different signals, each with its own
  626. meaning.  For example, the signal `SIGINT' means that the user has
  627. typed `C-c', or that some analogous thing has happened.
  628.    Each signal has a standard effect on the subprocess.  Most signals
  629. kill the subprocess, but some stop or resume execution instead.  Most
  630. signals can optionally be handled by programs; if the program handles
  631. the signal, then we can say nothing in general about its effects.
  632.    The set of signals and their names is defined by the operating
  633. system; Emacs has facilities for sending only a few of the signals that
  634. are defined.  Emacs can send signals only to its own subprocesses.
  635.    You can send signals explicitly by calling the functions in this
  636. section.  Emacs also sends signals automatically at certain times:
  637. killing a buffer sends a `SIGHUP' signal to all its associated
  638. processes; killing Emacs sends a `SIGHUP' signal to all remaining
  639. processes.  (`SIGHUP' is a signal that usually indicates that the user
  640. hung up the phone.)
  641.    Each of the signal-sending functions takes two optional arguments:
  642. PROCESS-NAME and CURRENT-GROUP.
  643.    The argument PROCESS-NAME must be either a process, the name of one,
  644. or `nil'.  If it is `nil', the process defaults to the process
  645. associated with the current buffer.  An error is signaled if
  646. PROCESS-NAME does not identify a process.
  647.    The argument CURRENT-GROUP is a flag that makes a difference when
  648. you are running a job-control shell as an Emacs subprocess.  If it is
  649. non-`nil', then the signal is sent to the current process-group of the
  650. terminal which Emacs uses to communicate with the subprocess.  If the
  651. process is a job-control shell, this means the shell's current subjob.
  652. If it is `nil', the signal is sent to the process group of the
  653. immediate subprocess of Emacs.  If the subprocess is a job-control
  654. shell, this is the shell itself.
  655.    The flag CURRENT-GROUP has no effect when a pipe is used to
  656. communicate with the subprocess, because the operating system does not
  657. support the distinction in the case of pipes.  For the same reason,
  658. job-control shells won't work when a pipe is used.  See
  659. `process-connection-type' in *Note Asynchronous Processes::.
  660.  - Function: interrupt-process &optional PROCESS-NAME CURRENT-GROUP
  661.      This function interrupts the process PROCESS-NAME by sending the
  662.      signal `SIGINT'.  Outside of Emacs, typing the "interrupt
  663.      character" (normally `C-c' on some systems, and `DEL' on others)
  664.      sends this signal.  When the argument CURRENT-GROUP is non-`nil',
  665.      you can think of this function as "typing `C-c'" on the terminal
  666.      by which Emacs talks to the subprocess.
  667.  - Function: kill-process &optional PROCESS-NAME CURRENT-GROUP
  668.      This function kills the process PROCESS-NAME by sending the signal
  669.      `SIGKILL'.  This signal kills the subprocess immediately, and
  670.      cannot be handled by the subprocess.
  671.  - Function: quit-process &optional PROCESS-NAME CURRENT-GROUP
  672.      This function sends the signal `SIGQUIT' to the process
  673.      PROCESS-NAME.  This signal is the one sent by the "quit character"
  674.      (usually `C-b' or `C-\') when you are not inside Emacs.
  675.  - Function: stop-process &optional PROCESS-NAME CURRENT-GROUP
  676.      This function stops the process PROCESS-NAME by sending the signal
  677.      `SIGTSTP'.  Use `continue-process' to resume its execution.
  678.      On systems with job control, the "stop character" (usually `C-z')
  679.      sends this signal (outside of Emacs).  When CURRENT-GROUP is
  680.      non-`nil', you can think of this function as "typing `C-z'" on the
  681.      terminal Emacs uses to communicate with the subprocess.
  682.  - Function: continue-process &optional PROCESS-NAME CURRENT-GROUP
  683.      This function resumes execution of the process PROCESS by sending
  684.      it the signal `SIGCONT'.  This presumes that PROCESS-NAME was
  685.      stopped previously.
  686.  - Function: signal-process PID SIGNAL
  687.      This function sends a signal to process PID, which need not be a
  688.      child of Emacs.  The argument SIGNAL specifies which signal to
  689.      send; it should be an integer.
  690. File: elisp,  Node: Output from Processes,  Next: Sentinels,  Prev: Signals to Processes,  Up: Processes
  691. Receiving Output from Processes
  692. ===============================
  693.    There are two ways to receive the output that a subprocess writes to
  694. its standard output stream.  The output can be inserted in a buffer,
  695. which is called the associated buffer of the process, or a function
  696. called the "filter function" can be called to act on the output.
  697. * Menu:
  698. * Process Buffers::       If no filter, output is put in a buffer.
  699. * Filter Functions::      Filter functions accept output from the process.
  700. * Accepting Output::      Explicitly permitting subprocess output.
  701.                             Waiting for subprocess output.
  702. File: elisp,  Node: Process Buffers,  Next: Filter Functions,  Up: Output from Processes
  703. Process Buffers
  704. ---------------
  705.    A process can (and usually does) have an "associated buffer", which
  706. is an ordinary Emacs buffer that is used for two purposes: storing the
  707. output from the process, and deciding when to kill the process.  You
  708. can also use the buffer to identify a process to operate on, since in
  709. normal practice only one process is associated with any given buffer.
  710. Many applications of processes also use the buffer for editing input to
  711. be sent to the process, but this is not built into Emacs Lisp.
  712.    Unless the process has a filter function (*note Filter Functions::.),
  713. its output is inserted in the associated buffer.  The position to insert
  714. the output is determined by the `process-mark' (*note Process
  715. Information::.), which is then updated to point to the end of the text
  716. just inserted.  Usually, but not always, the `process-mark' is at the
  717. end of the buffer.  If the process has no buffer and no filter
  718. function, its output is discarded.
  719.  - Function: process-buffer PROCESS
  720.      This function returns the associated buffer of the process PROCESS.
  721.           (process-buffer (get-process "shell"))
  722.                => #<buffer *shell*>
  723.  - Function: process-mark PROCESS
  724.      This function returns the marker which controls where additional
  725.      output from the process will be inserted in the process buffer.
  726.      When output is inserted, the marker is updated to point at the end
  727.      of the output.  This causes successive batches of output to be
  728.      inserted consecutively.
  729.      If PROCESS does not insert its output into a buffer, then
  730.      `process-mark' returns a marker that points nowhere.
  731.      Filter functions normally should use this marker in the same
  732.      fashion as is done by direct insertion of output in the buffer.  A
  733.      good example of a filter function that uses `process-mark' is
  734.      found at the end of the following section.
  735.      When the user is expected to enter input in the process buffer for
  736.      transmission to the process, the process marker is useful for
  737.      distinguishing the new input from previous output.
  738.  - Function: set-process-buffer PROCESS BUFFER
  739.      This function sets the buffer associated with PROCESS to BUFFER.
  740.      If BUFFER is `nil', the process will not be associated with any
  741.      buffer.
  742.  - Function: get-buffer-process BUFFER-OR-NAME
  743.      This function returns the process associated with BUFFER-OR-NAME.
  744.      If there are several processes associated with it, then one is
  745.      chosen.  (Presently, the one chosen is the one most recently
  746.      created.)  It is usually a bad idea to have more than one process
  747.      associated with the same buffer.
  748.           (get-buffer-process "*shell*")
  749.                => #<process shell>
  750.      If the process's buffer is killed, the actual child process is
  751.      killed with a `SIGHUP' signal (*note Signals to Processes::.).
  752. File: elisp,  Node: Filter Functions,  Next: Accepting Output,  Prev: Process Buffers,  Up: Output from Processes
  753. Process Filter Functions
  754. ------------------------
  755.    A process "filter function" is a function that receives the standard
  756. output from the associated process.  If a process has a filter, then
  757. *all* output from that process, that would otherwise have been in a
  758. buffer, is passed to the filter.  The process buffer is used for output
  759. from the process only when there is no filter.
  760.    A filter function must accept two arguments: the associated process
  761. and a string, which is the output.  The function is then free to do
  762. whatever it chooses with the output.
  763.    A filter function runs only while Emacs is waiting (e.g., for
  764. terminal input, or for time to elapse, or for process output).  This
  765. avoids the timing errors that could result from running filters at
  766. random places in the middle of other Lisp programs.  You may explicitly
  767. cause Emacs to wait, so that filter functions will run, by calling
  768. `sit-for', `sleep-for' or `accept-process-output' (*note Accepting
  769. Output::.).  Emacs is also waiting when the command loop is reading
  770. input.
  771.    Quitting is normally inhibited within a filter function--otherwise,
  772. the effect of typing `C-g' at command level or to quit a user command
  773. would be unpredictable.  If you want to permit quitting inside a filter
  774. function, bind `inhibit-quit' to `nil'.  *Note Quitting::.
  775.    Many filter functions sometimes or always insert the text in the
  776. process's buffer, mimicking the actions of Emacs when there is no
  777. filter.  Such filter functions need to use `set-buffer' in order to be
  778. sure to insert in that buffer.  To avoid setting the current buffer
  779. semipermanently, these filter functions must use `unwind-protect' to
  780. make sure to restore the previous current buffer.  They should also
  781. update the process marker, and in some cases update the value of point.
  782. Here is how to do these things:
  783.      (defun ordinary-insertion-filter (proc string)
  784.        (let ((old-buffer (current-buffer)))
  785.          (unwind-protect
  786.              (let (moving)
  787.                (set-buffer (process-buffer proc))
  788.                (setq moving (= (point) (process-mark proc)))
  789.      (save-excursion
  790.                  ;; Insert the text, moving the process-marker.
  791.                  (goto-char (process-mark proc))
  792.                  (insert string)
  793.                  (set-marker (process-mark proc) (point)))
  794.                (if moving (goto-char (process-mark proc))))
  795.            (set-buffer old-buffer))))
  796. The reason to use an explicit `unwind-protect' rather than letting
  797. `save-excursion' restore the current buffer is so as to preserve the
  798. change in point made by `goto-char'.
  799.    To make the filter force the process buffer to be visible whenever
  800. new text arrives, insert the following line just before the
  801. `unwind-protect':
  802.      (display-buffer (process-buffer proc))
  803.    To force point to move to the end of the new output no matter where
  804. it was previously, eliminate the variable `moving' and call `goto-char'
  805. unconditionally.
  806.    All filter functions that do regexp searching or matching should save
  807. and restore the match data.  Otherwise, a filter function that runs
  808. during a call to `sit-for' might clobber the match data of the program
  809. that called `sit-for'.  *Note Match Data::.
  810.    The output to the function may come in chunks of any size.  A program
  811. that produces the same output twice in a row may send it as one batch
  812. of 200 characters one time, and five batches of 40 characters the next.
  813.  - Function: set-process-filter PROCESS FILTER
  814.      This function gives PROCESS the filter function FILTER.  If FILTER
  815.      is `nil', then the process will have no filter.
  816.  - Function: process-filter PROCESS
  817.      This function returns the filter function of PROCESS, or `nil' if
  818.      it has none.
  819.    Here is an example of use of a filter function:
  820.      (defun keep-output (process output)
  821.         (setq kept (cons output kept)))
  822.           => keep-output
  823.      (setq kept nil)
  824.           => nil
  825.      (set-process-filter (get-process "shell") 'keep-output)
  826.           => keep-output
  827.      (process-send-string "shell" "ls ~/other\n")
  828.           => nil
  829.      kept
  830.           => ("lewis@slug[8] % "
  831.      "FINAL-W87-SHORT.MSS    backup.otl              kolstad.mss~
  832.      address.txt             backup.psf              kolstad.psf
  833.      backup.bib~             david.mss               resume-Dec-86.mss~
  834.      backup.err              david.psf               resume-Dec.psf
  835.      backup.mss              dland                   syllabus.mss
  836.      "
  837.      "#backups.mss#          backup.mss~             kolstad.mss
  838.      ")
  839.    Here is another, more realistic example, which demonstrates how to
  840. use the process mark to do insertion in the same fashion as is done when
  841. there is no filter function:
  842.      ;; Insert input in the buffer specified by `my-shell-buffer'
  843.      ;;   and make sure that buffer is shown in some window.
  844.      (defun my-process-filter (proc str)
  845.          (let ((cur (selected-window))
  846.                (pop-up-windows t))
  847.            (pop-to-buffer my-shell-buffer)
  848.      (goto-char (point-max))
  849.            (insert str)
  850.            (set-marker (process-mark proc) (point-max))
  851.            (select-window cur)))
  852. File: elisp,  Node: Accepting Output,  Prev: Filter Functions,  Up: Output from Processes
  853. Accepting Output from Processes
  854. -------------------------------
  855.    Output from asynchronous subprocesses normally arrives only while
  856. Emacs is waiting for some sort of external event, such as elapsed time
  857. or terminal input.  Occasionally it is useful in a Lisp program to
  858. explicitly permit output to arrive at a specific point, or even to wait
  859. until output arrives from a process.
  860.  - Function: accept-process-output &optional PROCESS SECONDS MILLISEC
  861.      This function allows Emacs to read pending output from processes.
  862.      The output is inserted in the associated buffers or given to their
  863.      filter functions.  If PROCESS is non-`nil' then this function does
  864.      not return until some output has been received from PROCESS.
  865.      The arguments SECONDS and MILLISEC let you specify timeout
  866.      periods.  The former specifies a period measured in seconds and the
  867.      latter specifies one measured in milliseconds.  The two time
  868.      periods thus specified are added together, and
  869.      `accept-process-output' returns after that much time whether or
  870.      not there has been any subprocess output.
  871.      Not all operating systems support waiting periods other than
  872.      multiples of a second; on those that do not, you get an error if
  873.      you specify nonzero MILLISEC.
  874.      The function `accept-process-output' returns non-`nil' if it did
  875.      get some output, or `nil' if the timeout expired before output
  876.      arrived.
  877.